Calling sequence and line styles

This section (not including the two large tables at the end) is a good introduction to how to use plt and the differences between plt and the native Matlab plot.

Usually, you will call plt with at least two arguments:

plt(x,y);

This plots the data in vector x along the horizontal axis and the data in vector y along the vertical axis. x and y may be row or column vectors. plt will transpose one of the arguments if needed to line things up, so x could be a row vector while y was a column vector. x and y must be the same length, however. If not you will get an error message saying that the vectors must be the same length.

If y is a real vector, plt(y) is equivalent to plt(1:length(y),y).

To plot more than one trace, include the x and y vectors for each trace in the argument list. For example, this command plots three traces:

plt(x1,y1,x2,y2,x3,y3)

Quite often several traces share the same x vector. In this case, we can simply repeat the x vector in the argument list, as in:

plt(x,y1,x,y2,x,y3)
or
plt(x,[y1;y2;y3]). (a shorthand way of writing the above).

That would work only if the y1,y2,y3 were row vectors. If they were column vectors you would need to write:

plt(x,[y1 y2 y3])

You can call plt using an output argument, which will return a column vector of trace handles. For example:

h = plt(x,[y1 y2 y3])

will return a 3 by 1 column vector h of handles. h(1) of course would be the line handle associated with the y1 trace. Most often when you type the plt command at the command prompt you don't need to save plt's return value. However, when plt is called from a program sometimes the line handles are needed to allow further manipulations of the plot.

If x and y are both matrices of the same size, plt(x,y) will create one trace per column.

None of this so far should come as a surprise since it is identical to Matlab's plot command.
Some of the ways that plt and plot differ will become clear from what follows.

With plot the data to be plotted must be passed in via the argument list.
However, you may call plt without any arguments, allowing you to choose the data to plot interactively.
Find out about this method here: The Workspace Plotter.

Unlike plot, plt will accept data passed in cell arrays. For example, the following two commands do the same thing:

plt(x,[y1; y2; y3])
plt(x,{y1; y2; y3})

Although in the example above, y1, y2, and y3 must be the same length so there isn't a big advantage for the cell array input. However, now consider these two commands (again, these two lines are equivalent to each other):

plt(x1,y1,x2,y2,x3,y3)
plt({x1 x2 x3},{y1 y2 y3})

With plot, you must use the first form because cell arrays are not allowed. You can't combine the arguments into vectors because they may be different lengths. When typing in the command window the first form is probably easier anyway, but inside a program, the second form is far more convenient, especially when the data is read from files.

If y is a complex vector, plt(y) is equivalent to plt(real(y),imag(y)). Matlab's native plot works that way too. Unlike plot, plt treats complex arguments this way no matter where they appear in the argument list. For instance if a and b are both complex, plt(a,b) is equivalent to plt(real(a),imag(a),real(b),imag(b)). (Why this doesn't work with plot has sometimes been a mystery and an annoyance to me.)

Also like the plot command you can include any line property in the argument list. For example:

plt(x,y,'LineWidth',2) is equivalent to set(plt(x,y),'LineWidth',2)

However, the behaviors of plt and plot differ in that with plot these line properties must appear after all the data vectors in the argument list. (plot gives an error otherwise). With plt the line properties may occur in the middle of the argument list. In that case, the line property is applied only to the lines defined earlier in the argument list. For example:

plt(x,[y1;y2],'Marker','Diamond',x,[y3;y4]);

only sets the Marker property for the first two traces. An equivalent to the above is:

a=plt(x,[y1;y2;y3;y4]); set(a(1:2),'Marker','Diamond');

By using cell arrays, you can set properties differently on each trace. For example:

plt(x,[y1;y2;y3],'LineWidth',{5 4 3},x,[y4;y5]);

This would set the LineWidth of the trace associated with y1,y2,y3 to 5,4,3 respectively while the remaining two traces (y4 & y5) would keep the default linewidth of 1. A column ({5;4;3}) would have worked equally as well. To accomplish the same width assignments using plot you would need the somewhat more cryptic:

set(plot(x,[y1;y2;y3;y4;y5]),{'LineWidth'},{5;4;3;1;1});

Two more examples:

plt(x,[y1;y2;y3;y4],'LineStyle',{'-' ':' '-.' 'none'});

plt(x,[y1;y2;y3],'Marker',{'square','none','+'});

This method of assigning properties works with any line property. In the two particular line properties used above, you could have replaced 'LineStyle' with 'Styles' and 'Marker' with 'Markers' and the results would be the same. Styles and Markers are not really line properties, however, plt allows you to use those alternate forms to allow some additional flexibility in how you write the parameter that follows it. (For example, a character array may be used in place of the cell array.) The details of the additional flexibility provided by using these two alternate parameters are described in the Trace properties section.

The special plot types vertical bars, error bars, and vector fields (arrows) are plotted with the help of auxiliary functions Pvbar, Pebar and Pquiv. The use of these functions is described in the Auxiliary functions section.

plt vs. pltinit

The code for the plotting package portion of this toolbox is broken up into these three routines:

pltinit.m	Contains the code used to create a new plt pseudo object which means creating a new plot axis or set of axes. This also normally means creating a new figure window as well. (The only exception to that is when the 'Fig' parameter is included in the parameter list.)
plt.m	Contains the code used to create or modify any of the remaining pseudo objects (including grid, edit, pop, slider, image, ColorPick, and HelpText) but not including the cursor pseudo object.
cur.m	Contains the code used to create or modify the cursor pseudo object.

From this description, you might expect that since all the command examples shown above create a new plot, that they should really be calling pltinit( ) instead of plt( ). While this is technically true, plt recognizes from the syntax when a new plot is being created and simply passes all of its arguments on to pltinit. The advantage of this is that "plt" is shorter and easier to type which is especially important when used from the command window. To create a new plot from a script or function, it is more a matter of taste which function you use. For a complicated gui, pltinit might be a better choice since it will make it easier to see where the plots are created.

This completes the introduction. What remains in this section and all the remaining help file sections might be too long and detailed to serve as an ideal way to learn about these parameters and commands. Perhaps an easier way to learn how to program with plt is to run thru all the demo programs (conveniently done with demoplt.m) while reading the comments at the top of each example program. The program comments may also be found next to a screen capture of each demo program in the Programming examples section . You will learn about nearly every plt parameter and option this way. Then you can use what follows merely as reference material.

Figure application data:

After a call to plt, the following information is available from the application data of the figure window as well as the application data of other objects:
(The quoted strings are case-sensitive.)

getappdata(gcf,'axis')	Returns a row vector of handles of the axes containing the plotted data. The first handle in the vector is the left-hand main plot. This is followed by the subplot axes (if any) from the bottom up. Finally, the last element of the vector will be the handle of the main plot right hand axis (if any).
findobj(gcf,'tag','click')	Similar to above except only a single axis handle is returned (the main plot left-hand axis)
get(ax,'user')	Returns the cursor ID for the axis with handle ax which may be any axis that appears in the vector returned from the command above.
getappdata(gcf,'cid')	Returns the cursor IDs for each axis, starting with the main (lower) axis and working upwards to include all the subplot axes. (There is not a cursor object associated with the right-hand axis since the main axis cursor also displays data from the right hand axis.)
getappdata(gcf,'Lhandles')	Returns a list of all handles of all data traces created by plt. Note that this is identical to the plt return value.
getappdata(ax,'Lhandles')	Each axis (including the right-hand axis) also has a 'Lhandles' application data value. This contains a list of all lines contained in that axis. The main (lower) plot is an exception since its Lhandles list includes the traces on both the left and right-hand axis.
findobj('name','Abc')	If the plt call includes a parameter such as 'FigName','Abc' then this command will return the handle of the figure window that plt created. This can be useful in programs that create multiple plt figures.
findobj(gcf,'user','TraceID')	Various plt arguments may be used to modify the location, appearance, or contents of the TraceID box. However, occasionally you may want to make further modifications after the plt call and this command will allow you to do that by returning the handle of the axis that is used as the TraceID box. An alternate way of finding this handle is to use the cur(CID,'obj') command. See the Cursor commands section for a description of this command.
findobj(gcf,'tag','MenuBox')	This command will return the handle of the MenuBox. Assuming the menu box is in its default configuration, a command such as: get(findobj(gcf,'tag','MenuBox'),'child') will return a list of text objects with string properties of: 'XY<->', 'Zout', 'Mark', 'Data', 'Grid', 'LinY', 'LinX', and 'Help'.
findobj(gcf,'user','grid')	This command returns a column vector containing the line handles of the plot grids for all the axes in the figure. If there is just a single axis (i.e. one grid object) then this is equivalent to plt('grid',0,'get').
getappdata(gcf,'params')	Returns a cell array list of the parameters specified on the plt command line. (All plt arguments are included except the arguments specifying the data arrays.)
getappdata(ax,'xstr')	Returns the value that was specified in the 'Xstring' parameter when plt was called. ax refers to the primary left-hand axis.
getappdata(ax,'ystr')	Returns the value that was specified in the 'Ystring' parameter when plt was called. ax refers to the primary left-hand axis.
getappdata(gcf,'multi')	Returns a column vector of handles to the objects used to render the Multi-cursor (the text objects, followed by the markers, followed by the dotted vertical line). If the multi-cursor is not currently enabled, then this vector will be empty.
getappdata(0,'Mver')	Returns a numerical value derived from the string returned by the Matlab version command. Before this string is converted to a number it is modified in a way that preserves chronological order (i.e. later versions will return a larger number). For example, in Matlab version '9.11' this root application data will be assigned a numerical value of 9.11 (i.e. the same as the string), however in Matlab version '9.8' this will be assigned a value of 9.08 (different from the numerical value of the Matlab version string). Some of the demo programs use constructs that are slightly different in different Matlab versions, so these programs use the 'Mver' application data so that these demos will run properly in any Matlab version.

Single argument actions:

The command strings here (as with most plt commands) are not case sensitive.
So for example "plt help" and "plt HELP" are equivalent.

plt help	Displays the plt help file. You could also use the functional form of this command: plt('help'). Alternatively, if you just want a one-page list of the plt parameters type type help plt.
plt version	Returns the plt version. Same as: plt('version')
plt save	Opens a dialog box allowing you to select a .plt figure file that can be opened later using the plt open item in the file menu. If you want to avoid the file dialog box add the file name as a 3rd argument (i.e. plt save filename). The use of these plt figure files is described in more detail in the Menu box section. Note that this command is also available from the file menu.
plt open	Opens a dialog box allowing you to select a .plt figure file that was saved using the plt save item in the file menu. If you want to avoid the file dialog box add the file name as a 3rd argument (i.e. plt open filename). Note that this command is also available from the file menu.
plt close	If a programming error causes plt to crash, you may find it difficult to close the plt figure windows (because they use the close request function). This command solves the problem by closing all currently open plt figure windows. Figure windows not created by plt are not closed. (And of course, you may also use the functional form.)
plt show	If the current figure was created by plt, then this command, or the equivalent functional form plt('show'), will return a list of trace numbers that are currently being displayed. For example, if you run the demo program "plt5.m" (which has five traces) and then turn off traces 3 and 4 (by clicking on their trace IDs) then this command will return [1 2 5] showing that those three traces are currently active. You can also use this command with an argument (the functional form only) from a program or the command window to set the traces you want active for the current figure. For example after running plt5.m, the command plt('show',2:5) will turn off the first trace while leaving the remaining four traces on. Note that the TraceIDs will change their appearance to indicate which traces are enabled just as if you had done the same operation by clicking on the trace names in the TraceID box. To disable all traces, use plt('show','') and to enable all traces, use plt('show','all') or plt('show',1:n) where n is the number of traces defined.
plt HelpText plt HelpText off plt HelpText on	The first two forms to the left (off or with no argument) delete the help text and the last form (on) recreates that help text again (which it can do by retrieving the help text information using getappdata(gcf,'helptext')). Help text is usually created by using the 'HelpText' parameter when the plt window is created (this is described in the Labels and figure properties section.) (And of course, you may also use the functional form, i.e. plt('HelpText','on');).
plt move	This command (which has the same effect as right-clicking on the delta cursor button) sets the current plt figure into its repositioning mode. This allows all gui objects to be resized and/or repositioned using the mouse. The new positions are displayed in the command window. Typing plt move a second time cancels the repositioning mode and returns the controls to their prior functions. Details may be found here: GUI building with plt